$webwork.htmlEncode($page.space.name) : 4 GeoServer Data Directory

Data Dir Introduction

The GeoServer Data Directory is the preferred place to store ones configuration for GeoServer. It includes the catalog.xml and services.xmlf files, which are the two primary configuration files. It also includes a number of support files, a styles/ directory of sld files, a featureTypes/ directory, that has config for each layer, and often it will contain a number of spatial files, in the data/ folder, since it's a convenient place to store them and pass around.

Configuration for GeoServer used to be stored directly in the webapp, but this had several disadvantages. First it makes upgrading a bit difficult, since one needs to copy the files out of the webapp, then put in the new war/install, and then replace the files. Some servlet containers additionally don't actually expand the war, which puts GeoServer configuration in some odd places, since most webapps don't really expect wars to be saving the config information directly in it. Which leads to the third strike against it - the common practice is to keep configuration by itself.

One thought to avoid some of this was to offer upgrade files, that didn't clobber the old embedded data/ directory. This has the disadvantage of requiring even more files to be uploaded for a release, and potentially confuses users. But the data_dir has several distinct advantages, the main one being it becomes possible to pass geoserver configurations around easily. With the GeoServer Data Dir, one can zip up their config and send it off to someone else. If shapefiles are used, all the data is included in the dir, as long as the shapefiles are referenced relatively. And if the other computer has access to the same database, if it's on the web, or they're on the same intranet, then configs for the db can also be passed along. All the shapefiles will be preconfigured. This also opens up the possibility of an app like udig creating a data_dir for use in GeoServer, which could be sent and easily configured. Indeed, we could start to offer an 'upload config' page that allows an Admin to dump a whole configuration to a server at once. This also will allow us to distribute many different sample GeoServer configurations, like a pre-set up TIGER dataset, some nice demos, an empty config, or preconfigured features for CITE conformance testing.

Using the Data Dir

Using the Data Dir is easy: You can define your geoserver data directory in three ways:

1."GEOSERVER_DATA_DIR" system property.

In the binary installs as of 1.3.0-RC7 we include the ability to read environment variables on windows and linux. So if you define a GEOSERVER_DATA_DIR variable, it will be instantly used in GeoServer.

Windows
Go to Control Panel -> System -> Advanced -> Enivornmental Variables, and click on the new button to create a user environment variable.
Name the variable: GEOSERVER_DATA_DIR
Give the value of the variable the fill location to your data directory.

export GEOSERVER_DATA_DIR=/home/cholmes/my-gs-dir/

Note that the latest binary releases come with a top level data directory, it's called data_dir/, and will be used by default. If you are upgrading GeoServer you can just copy the data_dir/ directory out and set it with the GEOSERVER_DATA_DIR environment variable.

If you are starting the java process of the servlet container directly, this can be set with the -D command:

"java -DGEOSERVER_DATA_DIR=..."

If you are running the war installation on your own servlet container, you can sometimes set java properties in a gui, or you can find the startup script that starts your servlet, and pass in the -D to the java process.

2. "GEOSERVER_DATA_DIR" in the web.xml document:

If you navigate to expanded geoserver war file, you can find the web.xml document in the [geoserver_install]/webapps/geoserver/WEB-INF directory. You can add a context param:

<context-param>
<param-name>GEOSERVER_DATA_DIR</param-name>
<param-value>c:\myGeoserverData</param-value>
</context-param>

Remember that if you have a system property defined, it will take precedence over the data dir declaration in the web.xml file

3. Defaults to the application root

The default location, if no system property (environment variable) is defined and no path is defined in the web.xml document:
[geoserver_install]/webapps/geoserver/conf

Creating a new Data Directory

Create a new empty directory

To make a new GeoServer Data Directory, you must first create a new directory somewhere on your computer. For this example let's say it's at:

Linux:
/home/cholmes/gs-conf/

Windows:
C:\data_dir\

Find your geoserver install

To create your data directory you must copy a set of files from your current GeoServer installation. To do this find the location of GeoServer.

[install location]/webapps/geoserver/conf

[install location]/data_dir

In war installations it will be in the webapps directory of your servlet containers:

[servlet container location]/webapps/geoserver/conf

Data Directory Contents

data_dir:
 - catalog.xml
 - services.xml
 - coverages\
 - data\
 - demo\
 - featureTypes\
 - plugins\
 - styles\
 - validation\

Copy services.xml and catalog.xml

The first two files to copy into your data directory are services.xml and catalog.xml, which are found in an existing geoserver data directory or [geoserver_install]/webapps/geoserver/WEB-INF. Copy them to the top of your directory, so you have:

/home/cholmes/gs-conf/catalog.xml

/home/cholmes/gs-conf/services.xml

Copy the contents of the rest of the data directory

Next you want to copy the other sub-directories of the already defined data directory, found at [geoserver_install]/webapps/geoserver/conf, to your new data directory.
These directories are:

coverages
data
demo
featureTypes
plugIns
styles
validation

featureTypes
styles

The data/ and coverage/ directories listed above are just arbitrarily named directories that hold sample data. You can name them something else if you wish.

Fix relative paths

If you need your data directory to be easily moved around from one server to another, you have to make the file paths independent of the current absolute location on the disk.
This can be achieved by putting all your file based data (shapefile, coverages) in the data directory and by referring to them with special relative paths.
Please not this is not necessary, absolute path are fine, this step is just needed if you want the data dir to be easily moved to other servers.

You can define shapefiles (and indeed all geographic files) in one of two ways, either with the absolute path:

file:/C:/Documents and Settings/Chris/My Documents/shapefiles/states.shp

file:data/actual_datasets/tutorial.shp

The relative one is still in relation to the data/ directory, so if you have relative shapefiles, you'll have to create a directory called data/ in your GeoServer data directory. Then you copy over all of the locations of your shapefiles. One of the ways that we used to recommend was putting this all in your featureTypes directory. If you did that, the easy way is to just also copy your featureTypes directory to data/ and everything should read fine. You should eventually move towards just defining your data directories within data/, and then point your DataStores directly at them.

Q: How do I get Tomcat to recognise the data_dir environment variable in Linux?

A: All you have to do to get Tomcat to recognise the environment variable is create a file called setenv.sh and save it in your Tomcat/bin directory. It will be sourced by catalina.sh if it exists.
Then, add the lines:

CATALINA_OPTS="-DGEOSERVER_DATA_DIR=/path/to/my/geoserver/data/directory"
  export CATALINA_OPTS

CATALINA_OPTS=" \
    -Xms64m -Xmx1024m \
    -XX:PermSize=32m -XX:MaxPermSize=128m \
    -server \
    -Djava.awt.headless=true \
    -DGEOSERVER_DATA_DIR=/path/to/my/geoserver/data/directory"
  export CATALINA_OPTS

Improve This Page

This is a wiki - you can edit this page. Please do so if you can improve it. Click the "Edit Page" button on the left of the page under the menu called "Page Operations".